/**
 * @(#)RolesManager.java Nov 10, 2006
 *
 * Copyright (c) 2005-2010 Psiqueware S.A. de C.V. All Rights Reserved.
 * This software is the proprietary information Psiqueware S.A. de C.V.
 * Use is subject to license terms.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
 * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * <br/>Usuario : AngelElectrico
 * <br/>Creaci&oacute;n: Nov 10, 2006 - 2:55:08 PM
 * <br/>
 * <br/>
 * <br/><t5>Cambios :</t5>
 * <br/><b>Fecha | Autor  |  Cambios</b>
 * <ul>
 * <li>Nov 10, 2006 | <a href = "mailto:AngelElectrico@PsiqueWare.com">Angel El&eacute;ctrico</a> | Creaci&oacute;n del Objeto.</li>
 *
 * </ul>
 */

package com.psiqueware.alheli.seguridad;

import com.psiqueware.alheli.dao.EnlaceTransaccional;
import com.psiqueware.alheli.manager.BaseManagerInterface;

import java.util.List;

/**
 * Controla la aplicaci&oacute;n de {@link Rol}es y {@link Permiso}s.
 * Versi&oacute;n transaccional.
 * <br/>Paquete Original: com.psiqueware.basico.seguridad
 * <br/>Nombre  Original: SeguridadModulosTManager
 * <br/>Oprima para ver : <a href="RolesManager.java.html"><i>C&oacute;digo Fuente</i> </a>
 *
 * @author <a href="mailto:AngelElectrico@PsiqueWare.com">Angel El&eacute;ctrico</a>
 * @version Revision: 1.1 Nov 10, 2006 2:55:08 PM
 */
public interface RolesManager extends BaseManagerInterface
{

    /**
     * Registra un {@link Permiso} en la seguridad para poder ser utilizado.
     *
     * @param permiso             {@link Permiso} a registrar.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @throws SeguridadException en caso de un error de acceso a persistencia.
     */
    void registraPermiso(final Permiso permiso, final String descripcionPermiso, final EnlaceTransaccional enlaceTransaccional) throws SeguridadException;

    /**
     * Devuelve un listado de {@link Permiso} registrados.
     *
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return {@link List} de {@link Permiso}.
     *
     * @throws SeguridadException en caso de un error de acceso a persistencia.
     */
    List<Permiso> listaPermisosRegistrados(final EnlaceTransaccional enlaceTransaccional) throws SeguridadException;

    /**
     * A&ntilde;ade un {@link Rol} a un {@link Credencial} dado.
     * Y persiste los cambios.
     *
     * @param rol                 a agregar.
     * @param usuarioDestino      {@link UsuarioSeguridad} al que se le va a agregar el {@link Rol}.
     * @param autoriza            {@link UsuarioSeguridad} que autoriza la operaci&oacute;n.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return <code>true</code> si la operaci&oacute;n se realiz&oacute; exitosamente; <code>false</code> en caso contrario.
     *
     * @throws SeguridadException en caso de no poder completar la operaci&oacute;n.
     * @noinspection CastToConcreteClass
     */
    boolean addRolUsuario(Rol rol, UsuarioSeguridad usuarioDestino, UsuarioSeguridad autoriza, final EnlaceTransaccional enlaceTransaccional) throws SeguridadException;

    /**
     * Remueve un {@link Rol} a un {@link Credencial} dado. Y persiste
     * los cambios.
     *
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     * @param rol                 a eliminar.
     * @param usuarioDestino      {@link UsuarioSeguridad} al que se le retir&oacute; el {@link Rol}.
     * @param autoriza            {@link UsuarioSeguridad} que autoriza la transacci&oacute;n.
     *
     * @return <code>true</code> si la operaci&oacute;n se realiz&oacute; exitosamente; <code>false</code> en caso contrario.
     *
     * @throws SeguridadException en caso de no poder completar la operaci&oacute;n.
     * @noinspection CastToConcreteClass
     */
    boolean removeRolUsuario(Rol rol, UsuarioSeguridad usuarioDestino, UsuarioSeguridad autoriza, final EnlaceTransaccional enlaceTransaccional) throws SeguridadException;

    /**
     * A&ntilde;ade un {@link Permiso} a un {@link Rol} dado.
     *
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     * @param permiso             a agregar.
     * @param rol                 al que se le va a agregar el {@link Permiso}.
     * @param autoriza            {@link UsuarioSeguridad} que autoriza la transacci&oacute;n.
     *
     * @return <code>true</code> si la operaci&oacute;n se fu&eacute; autorizada; <code>false</code> en caso contrario.
     *
     * @throws SeguridadException en caso de no poder persistir los cambios.
     * @noinspection CastToConcreteClass
     */
    boolean addPermisoRol(Permiso permiso, Rol rol, UsuarioSeguridad autoriza, final EnlaceTransaccional enlaceTransaccional) throws SeguridadException;

    /**
     * Remueve un {@link Permiso} a un {@link Rol} dado.
     *
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     * @param permiso             a remover.
     * @param rol                 de donde se va a eliminar el permiso.
     * @param autoriza            {@link UsuarioSeguridad} que autoriza la transacci&oacute;n.
     *
     * @return <code>true</code> si la operaci&oacute;n se realiz&oacute; exitosamente; <code>false</code> en caso contrario.
     *
     * @throws SeguridadException en caso de un error de acceso a persistencia.
     * @noinspection CastToConcreteClass
     */
    boolean removePermisoRol(Permiso permiso, Rol rol, UsuarioSeguridad autoriza, final EnlaceTransaccional enlaceTransaccional) throws SeguridadException;

    /**
     * Crea un nuevo {@link Rol} para una {@link Agrupacion} dado. Se encuentra persistido el {@link Rol} despu&eacute;s de
     * ejecutar esta operaci&oacute;n y es parte del {@link Agrupacion}.
     *
     * @param nombre              del {@link Rol}.
     * @param autoriza            {@link UsuarioSeguridad} que pretende autorizar la operaci&oacute;n. De &Eacute;l se toma el {@link Agrupacion} para el nuevo {@link Rol}.
     * @param enlaceTransaccional enlace para hacer at&oacute;micas las transacciones.
     *
     * @return {@link Rol} en caso de que la operaci&oacute;n fuera autorizada; <code>null</code> en caso contrario.
     *
     * @throws IllegalArgumentException si el rol que se quiere crear ya existe en el {@link Agrupacion}.
     * @throws SeguridadException       en caso de no poderse persistir los cambios.
     * @noinspection CastToConcreteClass, AssignmentToNull
     */
    Rol nuevoRol(String nombre, UsuarioSeguridad autoriza, final EnlaceTransaccional enlaceTransaccional) throws SeguridadException;
}
